# Troubleshooting Guide

## Common Issues

### "Manifest file is missing or unreadable"

**Problem:** Chrome can't find or read the manifest.json file.

**Solutions:**
1. Make sure you're loading the `dist` folder, not the root folder
2. Run `npm run build` to ensure the manifest is copied to `dist/`
3. Check that `dist/manifest.json` exists and has correct paths (without `dist/` prefix)
4. Verify the manifest.json is valid JSON (no syntax errors)

**Steps to fix:**
```bash
# Rebuild the extension
npm run build

# Verify manifest exists
ls dist/manifest.json

# Check manifest content (paths should NOT have 'dist/' prefix)
cat dist/manifest.json
```

### Extension loads but shows blank page

**Problem:** React app isn't loading.

**Solutions:**
1. Check browser console for errors (F12)
2. Verify all HTML files reference correct JS files
3. Ensure data files are copied to `dist/data/`
4. Check that Vite built all entry points correctly

**Debug steps:**
- Open Chrome DevTools (F12)
- Check Console tab for errors
- Check Network tab to see if files are loading
- Verify `dist/assets/` contains JS and CSS files

### History visualizations not working

**Problem:** Charts don't appear or show errors.

**Solutions:**
1. Grant history permission in Chrome extension settings
2. Check that Chart.js is properly imported
3. Verify browser history API is accessible
3. Check console for Chart.js errors

**Steps:**
- Go to `chrome://extensions/`
- Find your extension
- Click "Details"
- Ensure "History" permission is granted
- Reload the extension

### Audio not playing

**Problem:** Notification sounds or ambient sounds don't work.

**Solutions:**
1. Tone.js requires user interaction to initialize
2. Check browser console for audio context errors
3. Verify Tone.js is properly imported
4. Ensure audio permissions are granted

**Note:** Tone.js cannot run in service workers. Audio is handled via message passing to page contexts.

### Build errors

**Problem:** `npm run build` fails.

**Solutions:**
1. Clear node_modules and reinstall:
   ```bash
   rm -rf node_modules
   npm install
   ```

2. Check Node.js version (should be 18+):
   ```bash
   node --version
   ```

3. Clear Vite cache:
   ```bash
   rm -rf node_modules/.vite
   npm run build
   ```

4. Check for syntax errors in source files

### Icons not showing

**Problem:** Extension icons are missing.

**Solutions:**
1. Verify `icons/` folder exists in project root
2. Ensure icons are copied to `dist/icons/` after build
3. Check icon file names match manifest.json
4. Verify icon files are valid PNG images

**Fix:**
```bash
# Manually copy icons if needed
cp -r icons dist/
```

### Data files not loading

**Problem:** Longevity content or reminders not appearing.

**Solutions:**
1. Verify `data/` folder is copied to `dist/data/`
2. Check HTML files reference data scripts correctly
3. Ensure data files are loaded before React app
4. Check browser console for script loading errors

**Fix:**
```bash
# Manually copy data if needed
cp -r data dist/
```

## Verification Checklist

After building, verify:

- [ ] `dist/manifest.json` exists
- [ ] `dist/popup.html` exists
- [ ] `dist/newtab.html` exists
- [ ] `dist/breathing.html` exists
- [ ] `dist/longevity-history.html` exists
- [ ] `dist/background.js` exists
- [ ] `dist/assets/` contains JS and CSS files
- [ ] `dist/data/` contains data files
- [ ] `dist/icons/` contains icon files
- [ ] Manifest paths don't have `dist/` prefix

## Getting Help

If issues persist:

1. Check browser console for detailed error messages
2. Verify all dependencies are installed: `npm install`
3. Try a clean rebuild:
   ```bash
   rm -rf dist node_modules
   npm install
   npm run build
   ```
4. Check that you're loading the correct folder (`dist/`, not root)

